/**
 * Copyright (C) 2012 Foxit Corporation.
 * All Rights Reserved.
 *
 * The following code is copyrighted and contains proprietary information and trade secrets of Foxit Corporation.
 * You can only redistribute files listed below to customers of your application, under a written SDK license agreement with Foxit.
 * You cannot distribute any part of the SDK to general public, even with a SDK license agreement.
 * Without SDK license agreement, you cannot redistribute anything.
 *
 * @file fpdftext.h
 * @brief 	Header file for the Text module.
 * @details	The Text module offers:
 *			1. Methods for getting the data and the feature of of text and characters inside a page.
 *			2. Methods for searching text and characters in a page.
 *			3. Methods for getting the data and the feature of of weblinks inside a page.
 *			
 *			Before any operation, users should gain the reference of FGSPDFTextPageRef by using function ::FGSPDFTextLoadPage
 *			and remember to call function ::FPDF_Text_CloseTextPage to release the handle.
 * @note	If you want to purchase Foxit GSDK license and use ANY of the following functions, please
 *			request for enabling Base Data module explicitly. 
 */
 
 /** 
 * @addtogroup FGSPDFTEXT PDF Text
 * @brief Definitions and Methods in this module are included in fpdftext.h.
 */
 
 /** @{*/

#ifndef __FGSPDFTEXT__
#define __FGSPDFTEXT__

#ifndef __FGSPDFBASE__
    #include "fpdfbase.h"
#endif

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief Prepare the information about all characters in a page.
 *
 * @param[in]  page				Reference to a page.
 *
 * @return	a text page handle. If an error occurs, this will be set to <b>NULL</b>.
 *
 * @note The application must call ::FGSPDFTextClosePage to release the text page information. 
 */
FGSPDFTextPageRef FGSPDFTextLoadPage(FGSPDFPageRef page);

/**
 * @brief Release all resources allocated for a text page handle.   
 *			
 * @param[in] textPage			Reference to a page.
 *
 * @return	::kFGSErrorSuccess means load the text page successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet FGSPDFTextClosePage(FGSPDFTextPageRef textPage);

/**
 * @brief Get the count of characters in a page. 
 *
 * @details Generated characters, such as additional space and new line characters, are also counted.
 *			Characters in a page are from a "stream". Inside the stream, each character has an index. 
 *			Index parameters are used in most of the Text module functions. The first character in 
 *			the page has an index value of zero.
 *			
 * @param[in]  textPage			Reference to a page.
 *
 * @return	the count of characters in the page. If an error occurs, this will be set to 0.
 *
 */
SInt32 FGSPDFTextCountChars(FGSPDFTextPageRef textPage);

/**
 * @brief Extract a Unicode text string from the page.    
 *			
 * @param[in]  textPage			Reference to a text page.
 * @param[in]  index			A zero-based index of the start character.
 * @param[in]  count			The count of characters to be extracted.
 *
 * @return	The unicode representation of the character specified by the parameter <i>index</i>.
 *			If a character is not encoded in Unicode (the Foxit engine will not 
 *			convert it to unicode), this parameter will be set to 0. The user should release the string by calling <b>CFRelease</b>.
 *
 * @note When <i>count</i> = -1 or the result of (<i>index</i> + <i>count</i>)is larger than the whole count of characters in the input text page, 
 *		 it means this function will get all characters in the text page from the index <i>index</i>.<br>
 *
 */
    
CFStringRef FGSPDFTextCopyText(FGSPDFTextPageRef textPage, SInt32 index, SInt32 count);

/** 
 * @brief Count number of rectangular areas occupied by a segment of texts.  
 *
 * @details This function, along with ::FGSPDFTextSelectRectText, can be used to detect the position 
 *			of the text segment on a page. When highlighting text, it is the area corresponding to 
 *			the text segment that is colored in. It will automatically merge small character 
 *			boxes into bigger ones if those characters are on the same line and use the same font settings. 
 *
 * @param[in] textPage			Reference to a text page.
 * @param[in] startIndex		A zero-based index for the start character.
 * @param[in] textCount			The count of characters to be extracted.  -1 means to count all the rectangles in the page. 
 *
 * @return     That receives the count of rectangles. Zero means error.
 *
 * @note The value of the parameter <i>textCount</i> should be greater than or equal to -1.
 *
 */
SInt32 FGSPDFTextCountTextRects(FGSPDFTextPageRef textPage, SInt32 startIndex, SInt32 textCount);

/** 
 * @brief Get a rectangular area from the result generated by ::FGSPDFTextCountTextRects.   
 *
 * @param[in] textPage			Reference to a text page.
 * @param[in] index				A zero-based index the rectangle to be got.
 * @param[out] rect				The rectangle.
 *
 * @return	A rectangle of the particular index-based text segment.
 *
 * @note Assume that <i>nCount</i> is the result generated by ::FGSPDFTextCountTextRects.<br>
 *		 The range of <i>index</i> should be 0 to (<i>nCount</i> - 1), including 0 and (<i>nCount</i> - 1).
 *
 */
CGRect FGSPDFTextGetTextRect(FGSPDFTextPageRef textPage, SInt32 index);

/** 
 * @brief Get the count of selected text segments. 
 *
 * @param[in] textPage			Reference to a text page.
 *
 * @return	The count of segments.
 *
 */
SInt32 FGSPDFTextCountSelectedSegments(FGSPDFTextPageRef textPage);

/** 
 * @brief Get a particular segment. The count of segments is returned by ::FGSPDFTextCountSelectedSegments. 
 *
 * @param[in] textPage			Reference to a text page.
 * @param[in] index				A zero-based index of the segment to be got.
 * @param[out] startIndex		An integer that receives the start character index of the segment.
 * @param[out] textCount		An integer that receives the count of characters in the segment. 
 *
 * @return ::kFGSErrorSuccess means release a search context successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 * @note Assume that <i>nCount</i> is the result generated by ::FGSPDFTextCountSelectedSegments.<br>
 *		 The range of <i>index</i> should be 0 to (<i>nCount</i> - 1), including 0 and (<i>nCount</i> - 1).
 *
 */
FGSErrorRet FGSPDFTextGetSelectedSegment(FGSPDFTextPageRef textPage, SInt32 index, SInt32* startIndex, SInt32* count);


/**
 * @brief Prepare to select text by specify a rectangle area.   
 *			
 * @param[in]  page             Reference to a text page.
 * @param[in]  rect             Used to specify a rectangle area.
 *
 * @return	::kFGSErrorSuccess means get the unicode successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet	FGSPDFTextSelectRectText(FGSPDFTextPageRef page, CGRect rect);

/**
 * @brief Prepare to select text by specify two points, the selected area expands to adjacent chars in the same paragraph.   
 *			
 * @param[in]  page             Reference to a text page.
 * @param[in]  startpos         Used to specify the start point.
 * @param[in]  endpos           Used to specify the end point.
 *
 * @return	::kFGSErrorSuccess means get the unicode successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet FGSPDFTextSelectParagraphText(FGSPDFTextPageRef page, CGPoint startpos, CGPoint endpos);

/**
 * @brief	Get the count of selected rectangles in a page. 
 *		
 * @param[in]  textPage         Reference to a text page.		
 *
 * @return	The count of selected rectangles in the page. If an error occurs, this will be set to 0.
 *
 */
SInt32 FGSPDFTextCountSelectedRects(FGSPDFTextPageRef textPage);

/**
 * @brief Get the selected rectangles in a page.   
 *			
 * @param[in]  textPage         Reference to a text page.
 * @param[in]  index            the index of the rectangle.
 *
 * @return	The selected rectangle in a page.
 *
 */
CGRect FGSTextGetSelectedRect(FGSPDFTextPageRef textPage, SInt32 index);

/**
 * @brief Get the unicode representation of characters selected in a page.   
 *			
 * @param[in]  textPage			Reference to a text page.
 *
 * @return	The unicode representation of the character specified by the parameter <i>index</i>.
 *			If a character is not encoded in Unicode (the Foxit engine will not 
 *			convert it to unicode), this parameter will be set to 0. The user should release the string by calling <b>CFRelease</b>.
 */
CFStringRef FGSTextCopySelectedText(FGSPDFTextPageRef textPage);

/**
 * @brief Search a pattern in a page quickly, without the page having been parsed.
 *
 * @details This function does a rough and quick search in a page, before the page is loaded. 
 *			The quick search will not generate an exact result saying where the pattern is
 *			found, and, it might be possible if a quick search result is "pattern found", and
 *			a real search for the same pattern, in the same page, will result in "not found".<br>
 *			However, if quick search doesn't find a pattern in a page, then we can be sure the
 *			pattern won't be found in this page when we do a real search. So, this function is 
 *			very useful when we search in a multiple-page document, and we want to quickly skip
 *			those pages in which the pattern can't possibly be found.
 *
 * @param[in] document          AReference to a document.
 * @param[in] page_index		A zero-based index of the page.
 * @param[in] pattern			A zero-terminated unicode string to be found. 
 * @param[in] case_sensitive	Non-zero means case-sensitive searching, while zero means case-insensitive.
 *
 * @return	::kFGSErrorSuccess means success.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet FGSPDFTextQuickSearch(FGSPDFDocumentRef document, SInt32 page_index, CFStringRef pattern, SInt32 case_sensitive);

/** 
 * @brief Start a search. 
 *
 * @param[in]  textPage			Reference to a text page.
 * @param[in]  findWhat			A unicode match pattern. <br>
 *								If this parameter is <b>NULL</b> or the content to be find is <b>NULL</b>,
 *								the function will return ::kFGSErrorParam and set <i>searchHandle</i> to <b>NULL</b>.
 * @param[in]  flags			Indicate the find options.  Can be one of the following: <br>
 *								<ul>
 *									<li>::kFGSPDFMatchCase</li>
 *									<li>::kFGSPDFMatchWholeWord</li>	
 *								</ul>
 * @param[in]  startIndex		A zero-based index specifying the character from which the search will start. -1 means the end of the page.<br>		
 *
 * @return	A search context handle. ::FGSPDFTextCloseSearch must be called to release this handle.
 * @note Assume that <i>count</i> means the count of charaters in the page. So the range of the parameter <i>startIndex</i> is from 0 to (<i>count</i> - 1).
 */
FGSPDFTextSearchHandleRef FGSPDFTextStartSearch(FGSPDFTextPageRef textPage, CFStringRef findWhat, FGSPDFSearchFlag flags, SInt32 startIndex);

/** 
 * @brief Search in the direction from page start to end. 
 *
 * @param[in]  handle			Reference to a search context. 
 *
 * @return	::kFGSErrorSuccess means find the next matched content successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet FGSPDFTextSearchNext(FGSPDFTextSearchHandleRef searchhandle);

/** 
 * @brief Search in the direction from page end to start. 
 *
 * @param[in]  handle			Reference to a search context. 
 *
 * @return	::kFGSErrorSuccess means find the previous matched content successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet FGSPDFTextSearchPrev(FGSPDFTextSearchHandleRef searchhandle);

/** 
 * @brief Get the index and count of matched characters in the searched result. 
 *
 * @param[in] search			Reference to a search context.
 * @param[out] startIndex		An integer object that receives the start index of matched characters. 
 * @param[out] count			An integer object that receives the count of matched characters. 
 *
 * @return	::kFGSErrorSuccess means release a search context successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet FGSPDFTextGetSearchedResult(FGSPDFTextSearchHandleRef searchhandle, SInt32* startIndex, SInt32* count);

/**
 * @brief	Get the count of searched rectangles in a page. 
 *		
 * @param[in]  searchhandle		Reference to a text page.		
 *
 * @return	The count of searched rectangles in the page. If an error occurs, this will be set to 0.
 *
 */
SInt32 FGSPDFTextCountSearchedRects(FGSPDFTextSearchHandleRef searchhandle);

/**
 * @brief	Get the searched rectangles in a page.   
 *			
 * @param[in]  searchhandle		Reference to a text page.
 * @param[in]  index			The index of the rectangle.
 *
 * @return	The searched rectangle in a page.
 *
 */
CGRect FGSPDFTextGetSearchedRect(FGSPDFTextSearchHandleRef searchhandle, SInt32 index);

/** 
 * @brief Release a search context.     
 *
 * @param[in] searchhandle		Reference to a search context. 
 *
 * @return	::kFGSErrorSuccess means release a search context successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet FGSPDFTextCloseSearch(FGSPDFTextSearchHandleRef searchhandle);

/**
 * @brief Process the page text for URL formatted text.
 *
 * @details This function must be called before any other extracted link related function can be called for the page.
 *
 * @param[in] textPage          Reference to a text page.
 *
 * @return	an extracted link handle
 *
 */
FGSPDFPageLinkRef FPDFTextLoadWebLinks(FGSPDFTextPageRef textPage);

/**
 * @brief	Get number of URL formatted strings inside a page.
 *
 * @param[in] linkPage          Reference to An extracted links.
 *
 * @returnt	The count of links.
 *
 */
SInt32 FGSPDFTextCountWebLinks(FGSPDFPageLinkRef linkPage);

/**
 * @brief	Get a URL destination associated with a particular extracted hyperlink.
 *
 * @details If the parameter <i>buffer</i> is <b>NULL</b>, this function will set the data size to the parameter <i>buflen</i> as a result.
 *
 * @param[in]  linkPage			Reference to An extracted links.
 * @param[in]  linkIndex		A zero-based index of the link.
 *
 * @return	The URL destination.
 */
CFStringRef FGSPDFTextCopyLinkURI(FGSPDFPageLinkRef linkPage, SInt32 linkIndex);

/**
 * @brief Get the count of areas (rectangles) for an extracted link.
 *
 * @param[in]	linkPage		Reference to An extracted links.
 * @param[in]	linkIndex		A zero-based index of the link.
 *
 * @return	The count of quadrilaterals.
 *
 */
SInt32 FGSPDFTextCountLinkRects(FGSPDFPageLinkRef linkPage, SInt32 linkIndex);

/**
 * @brief Get a particular rectangle for an extracted link.
 *
 * @details The result in the parameter <i>points</i> array are the values of X/Y-coordinate for the four vertices
 *			of the rectangle. <br>Vertices are in the following order: lower left, lower
 *			right, upper right, upper left.
 *
 * @param[in] linkPage			Reference to An extracted links handle.
 * @param[in] linkIndex			A zero-based index of the link.
 * @param[in] areaIndex			A zero-based index of the quadrilateral.
 *
 * @return	A particular rectangle for an extracted link.
 *
 */
CGRect FGSPDFTextGetLinkRect(FGSPDFPageLinkRef linkPage, SInt32 linkIndex, SInt32 areaIndex); 

/**
 * @brief Release extracted hyperlink information.
 *
 * @param[in] linkPage			Reference to An extracted links handle.
 *
 * @return	::kFGSErrorSuccess means release extracted hyperlink information successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFTextCloseWebLinks(FGSPDFPageLinkRef linkPage);


/** 
 * @name FGSPDFTEXT Enumeration Types
 */
/**@{*/
/**
 * @brief Enum Definitions for text order flag
 */
enum {
	/** @brief Text stream order */
    kFGSPDFTextStreamOrder          = 0,
	/** @brief Text display order */
    kFGSPDFTextDisplayOrder         = 1,
};
/** @brief Alias of enumeration for text order flag. */
typedef UInt32 FGSPDFTextFlag;
/**@}*/

#ifdef __cplusplus
};
#endif

#endif // _FPDFTEXT_H_
/**@}*/

